Writing scenes
Writing scenes for Kobold Adventure is rather easy. Scenes are a combination of HTML, CSS and JavaScript. If you are at all familiar with creating simple websites, then making a Kobold Adventure scene will be a piece of cake. Let's get started, shall we?
The basics
A very basic scene needs only four things.
TODO: FINISH THIS SECTION
Writing style
TODO: FINISH THIS SECTION
Scene life cycle
TODO: FINISH THIS SECTION
index.html
<div class="koboldadventurecontent">
,
and it must end with
<div class="koboldadventurefinish"></div></div>
.
These are what we call the begin and end tags of the scene. All of the scene's content, including JavaScript and CSS styles will go in between these two tags.
TODO: FINISH THIS SECTION
Kobold preprocessor
The Kobold preprocessor allows you to make your scenes a more dynamic by letting you write JavaScript code inside of regular text.
Token | Use | Effect |
---|---|---|
$print() | Any JavaScript. "Show stuff" | Anything between the braces will be parsed as JavaScript. The result will be printed into the scene. Can theoretically be used to do anything, but should only be used if no other, more specific token is available. |
$pri() | Shorthand for $print(). | |
$p() | Shorthand for $pri(). | |
$show() | Alias for $print(). | |
$sh() | Shorthand for $show(). | |
$function() | Regular functions. Alias for $print(). | |
$fun() | Shorthand for $function(). | |
$unf() | Alias for $fun(). | |
$method() | Regular methods. "Do stuff" | Anything between the braces will be parsed as JavaScript. The result will be discarded. Should only be used if no other, more specific token is available. |
$meth() | Shorthand for $method(). | |
$do() | Alias for $method(). | |
$d() | Shorthand for $do(). | |
$kobold() | Kobold object functions and variables. | Anything between the braces will be parsed as a kobold object function or variable. Variables will be printed. Functions will be executed and then the result will be printed. |
$kob() | Shorthand for $kobold(). | |
$k() | Shorthand for $kob(). | |
$nobold() | Kobold object methods. | Anything between the braces will be parsed as a kobold object method. The method will be executed. The result will not be printed. |
$nob() | Shorthand for $nobold(). | |
$n() | Shorthand for $nob(). | |
$scene() | Scene object functions. | Anything between the braces will be parsed as a scene object function or variable. Variables will be printed. Functions will be executed and then the result will be printed. |
$sc() | Shorthand for $scene(). | |
$s() | Shorthand for $sc(). | |
$scenem() | Scene object methods. | Anything between the braces will be parsed as a scene object method. The method will be executed. The result will not be printed. |
$scenedo() | Alias for $scenem(). | |
$scdo() | Shorthand for $scenedo(). | |
$sdo() | Shorthand for $scdo(). | |
$sc2() | Alias for $scdo(). | |
$s2() | Shorthand for $sc2(). |
NOTE: do NOT put any unclosed parenthesis inside of preprocessor directive. Not even within strings. This breaks the preprocessor. Closed parenthesis are fine. Example: $show("I like (.)(.)") is fine. $show("I am sad :(") will break. $do(myFunction("I am happy :)")) will break.
TODO: FINISH THIS SECTION
init.js
TODO: FINISH THIS SECTION
afterload.js
TODO: FINISH THIS SECTION
Choices
Arguably the hardest part of writing a scene is not the writing itself, but rather adding code that will enable the selection of choices. Luckily, Kobold Adventure provides a flexible way of handling this aspect of scene writing, called the simpleChoice framework. First, we will detail the different components of choice selection code. Then we will show an example of doing it the hard way. Finally, we will refactor this example to the simpleChoice framework.
TODO: FINISH THIS SECTION
Useful functions
Here are a few JavaScript functions which may be called from anywhere within your scene. They provide basic functionality such as animation, description fetching and theme changing.
Animation
There are two main methods used for animation: animateAddClass and animateRemoveClass. Both of these methods have five different levels of speed: very fast, fast, regular, slow and very slow. This gives us the following ten functions to work with:
animateRemoveClassVeryFast(elements, toRemove)
animateRemoveClassFast(elements, toRemove)
animateRemoveClass(elements, toRemove)
animateRemoveClassSlow(elements, toRemove)
animateRemoveClassVerySlow(elements, toRemove)
animateAddClassVeryFast(elements, toAdd)
animateAddClassFast(elements, toAdd)
animateAddClass(elements, toAdd)
animateAddClassSlow(elements, toAdd)
animateAddClassVerySlow(elements, toAdd)
As you may have noticed, each of these functions has exactly two arguments. The former is always the set of elements to which to apply the change. The latter indicates the CSS class which should be added or removed. Note that certain CSS attributes, such as font-weight, can not be animated.
Example
Say we have a <div>
with id="animateclasschange"
and class="whitebg"
. Something like this:
<div id="animateclasschange" class="whitebg">
content
</div>
We want to remove the whitebg
class, whilst animating the changes. We do this by using the
animateRemoveClass
function.
var elements = $("#animateclasschange"); // Select the element using jQuery
var classToRemove = "whitebg"; // Specify the class to remove
animateRemoveClass(elements, classToRemove); // Call the function
We can add the class once more by calling the animateAddClass
function in a very similar manner.
var elements = $("#animateclasschange"); // Select the element using jQuery
var classToAdd = "whitebg"; // Specify the class to add
animateAddClass(elements, classToAdd); // Call the function
Interactive example
Final notes
While transitions are undoubtedly a neat feature, and they can spruce up a scene quite a bit, try not to overuse them. They are time consuming, and if you cram too many of them in a single page, they might begin to annoy the user.
Note that in the above example, the animation breaks when you rapidly mash both of the buttons in quick succession. This is due to the way that class transitions are handled by the Kobold Adventure framework. While the animation breaking isn't a big deal, it is advised not to allow these functions to be alternatingly called in quick succession on the same element. In other words: don't allow the users to toggle a class on and off like in the example above. Instead, only allow them to do either one or the other.
Changing themes
In order to change the entire color scheme of the game for the duration of your scene, you can make use of a theme. Themes are a collection of CSS rules that define four colors: the main color, the detail color, the background color and the text color. Making use of a theme can make your scene a lot more immersive, yet care should be taken to avoid overdoing it.
Applying a theme is rather easy. All you have to do is call the JavaScript function changeTheme
.
It takes only one parameter: the theme you wish to change to. Note that this function takes over a second to completely change
the theme, and during that duration no animations will be available. This function is rather unsafe to use, because you can't
guarantee the user won't change tabs, press buttons or do other stuff during the transition, which might lead to certain
animations breaking for the remainder of the session.
So why would you ever use changeTheme
? Because it's simple. There is, however, a more complex
alternative called changeThemeCallback
. This function takes two parameters: the theme you wish
to change to, and a callback function that will be called once the theme change is complete. While inherently having the same
issues as changeTheme
, you can manually disable UI elements prior to calling it, and then
re-enable them in the callback function. In a later version of Kobold Adventure, a simpler way of doing this will be provided.
Writing your own theme
TODO: FINISH THIS SECTION